<!DOCTYPE html><!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--><!--[if gt IE 8]><!--><html class="no-js" lang="en"><!--<![endif]--><head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  
  <link rel="canonical" href="https://sequelize.org/v3/docs/api/associations/belongs-to-many/">
  <link rel="shortcut icon" href="/v3/favicon.ico">
  
  <title>BelongsToMany (n:m) - Sequelize | The Node.js / io.js ORM for PostgreSQL, MySQL, SQLite and MSSQL</title>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700">

  <link rel="stylesheet" href="/v3/css/theme.css">
  <link rel="stylesheet" href="/v3/css/theme_extra.css">
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css">
  <link href="/v3/css/custom.css" rel="stylesheet">
  
  <script>
    // Current page data
    var mkdocs_page_name = "BelongsToMany (n:m)";
    var mkdocs_page_input_path = "api/associations/belongs-to-many.md";
    var mkdocs_page_url = "/api/associations/belongs-to-many/";
  </script>
  
  <script src="/v3/js/jquery-2.1.1.min.js" defer=""></script>
  <script src="/v3/js/modernizr-2.8.3.min.js" defer=""></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
  <script>hljs.initHighlightingOnLoad();</script> 
<meta name="robots" content="noindex"></head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
    <div class="wy-side-scroll">
      <div class="wy-side-nav-search">
        <a href="/v3" class="icon icon-home"> Sequelize | The Node.js / io.js ORM for PostgreSQL, MySQL, SQLite and MSSQL</a>
        <div role="search">
  <form id="rtd-search-form" class="wy-form" action="/v3/search.html" method="get">
      <input type="text" name="q" placeholder="Search docs" title="Type search term here">
  </form>
</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="/v3">Home</a>
                    </li>
                </ul>
                <p class="caption"><span class="caption-text">Documentation</span></p>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/getting-started/">Getting Started</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/schema/">Working with table schemas</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="#">Models</a>
    <ul>
                <li class="toctree-l2"><a class="reference internal" href="/v3/docs/models-definition/">Definition</a>
                </li>
                <li class="toctree-l2"><a class="reference internal" href="/v3/docs/models-usage/">Usage</a>
                </li>
    </ul>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/querying/">Querying</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/scopes/">Scopes</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/instances/">Instances</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/associations/">Relations / Associations</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/hooks/">Hooks</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/transactions/">Transactions</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/legacy/">Working with legacy tables</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/raw-queries/">Raw queries</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/docs/migrations/">Migrations</a>
                    </li>
                </ul>
                <p class="caption"><span class="caption-text">API</span></p>
                <ul class="current">
                    <li class="toctree-l1"><a class="reference internal" href="/v3/sequelize/">Sequelize</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/model/">Model</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/instance/">Instance</a>
                    </li>
                    <li class="toctree-l1 current"><a class="reference internal current" href="#">Associations</a>
    <ul class="current">
                <li class="toctree-l2"><a class="reference internal" href="/v3/api/">Overview</a>
                </li>
                <li class="toctree-l2"><a class="reference internal" href="/v3/api/belongs-to/">BelongsTo (1:1)</a>
                </li>
                <li class="toctree-l2"><a class="reference internal" href="/v3/api/has-one/">HasOne (1:1)</a>
                </li>
                <li class="toctree-l2"><a class="reference internal" href="/v3/api/has-many/">HasMany (1:m)</a>
                </li>
                <li class="toctree-l2 current"><a class="reference internal current" href="./">BelongsToMany (n:m)</a>
    <ul class="current">
    <li class="toctree-l3"><a class="reference internal" href="#getassociationsoptions-promisearrayinstance">getAssociations([options]) -&gt; Promise.&lt;Array.&lt;Instance&gt;&gt;</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#setassociationsnewassociations-options-promise">setAssociations([newAssociations], [options]) -&gt; Promise</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#addassociationsnewassociations-options-promise">addAssociations([newAssociations], [options]) -&gt; Promise</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#addassociationnewassociation-options-promise">addAssociation([newAssociation], [options]) -&gt; Promise</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#createassociationvalues-options-promise">createAssociation([values], [options]) -&gt; Promise</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#removeassociationoldassociated-options-promise">removeAssociation([oldAssociated], [options]) -&gt; Promise</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#removeassociationsoldassociated-options-promise">removeAssociations([oldAssociated], [options]) -&gt; Promise</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#hasassociationinstance-options-promise">hasAssociation([instance], [options]) -&gt; Promise</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#hasassociationsinstances-options-promise">hasAssociations([instances], [options]) -&gt; Promise</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#countassociationsoptions-promiseint">countAssociations([options]) -&gt; Promise.&lt;Int&gt;</a>
    </li>
    </ul>
                </li>
    </ul>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/hooks/">Hooks</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/transaction/">Transaction</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/datatypes/">Datatypes</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/deferrable/">Deferrable</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/errors/">Errors</a>
                    </li>
                </ul>
                <p class="caption"><span class="caption-text">Misc</span></p>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/changelog/">Changelog</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="/v3/imprint/">Imprint</a>
                    </li>
                </ul>
      </div>
    </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="/v3">Sequelize | The Node.js / io.js ORM for PostgreSQL, MySQL, SQLite and MSSQL</a>
      </nav>

      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="/v3">Docs</a> »</li>
    
      
        
          <li>API »</li>
        
      
        
          <li>Associations »</li>
        
      
    
    <li>BelongsToMany (n:m)</li>
    <li class="wy-breadcrumbs-aside">
      
        <a href="https://github.com/sequelize/sequelize/edit/master/docs/api/associations/belongs-to-many.md" class="icon icon-github"> Edit on GitHub</a>
      
    </li>
  </ul>
  
  <hr>
</div>

          <div role="main">
            <div class="section">
              
                <p><a name="belongstomany"></a></p>
<h1 id="mixin-belongstomany">Mixin BelongsToMany</h1>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L41">View code</a></p>
<p>Many-to-many association with a join table.</p>
<p>When the join table has additional attributes, these can be passed in the options object:</p>
<pre><code class="language-js">UserProject = sequelize.define('user_project', {
  role: Sequelize.STRING
});
User.belongsToMany(Project, { through: UserProject });
Project.belongsToMany(User, { through: UserProject });
// through is required!

user.addProject(project, { role: 'manager', transaction: t });
</code></pre>
<p>All methods allow you to pass either a persisted instance, its primary key, or a mixture:</p>
<pre><code class="language-js">Project.create({ id: 11 }).then(function (project) {
  user.addProjects([project, 12]);
});
</code></pre>
<p>In the API reference below, replace <code>Assocation(s)</code> with the actual name of your association, e.g. for <code>User.belongsToMany(Project)</code> the getter will be <code>user.getProjects()</code>.</p>
<hr>
<p><a name="getassociations"></a></p>
<h2 id="getassociationsoptions-promisearrayinstance"><code>getAssociations([options])</code> -&gt; <code>Promise.&lt;Array.&lt;Instance&gt;&gt;</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L209">View code</a></p>
<p>Get everything currently associated with this, using an optional where clause.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[options]</td>
<td>Object</td>
<td></td>
</tr>
<tr>
<td>[options.where]</td>
<td>Object</td>
<td>An optional where clause to limit the associated models</td>
</tr>
<tr>
<td>[options.scope]</td>
<td>String | Boolean</td>
<td>Apply a scope on the related model, or remove its default scope by passing false</td>
</tr>
<tr>
<td>[options.schema]</td>
<td>String</td>
<td>Apply a schema on the related model</td>
</tr>
</tbody>
</table>
<hr>
<p><a name="setassociations"></a></p>
<h2 id="setassociationsnewassociations-options-promise"><code>setAssociations([newAssociations], [options])</code> -&gt; <code>Promise</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L219">View code</a></p>
<p>Set the associated models by passing an array of instances or their primary keys. Everything that it not in the passed array will be un-associated.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[newAssociations]</td>
<td>Array.&lt;Instance | String | Number&gt;</td>
<td>An array of instances or primary key of instances to associate with this. Pass <code>null</code> or <code>undefined</code> to remove all associations.</td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>Options passed to <code>through.findAll</code>, <code>bulkCreate</code>, <code>update</code> and <code>destroy</code>. Can also hold additional attributes for the join table</td>
</tr>
<tr>
<td>[options.validate]</td>
<td>Object</td>
<td>Run validation for the join model</td>
</tr>
</tbody>
</table>
<hr>
<p><a name="addassociations"></a></p>
<h2 id="addassociationsnewassociations-options-promise"><code>addAssociations([newAssociations], [options])</code> -&gt; <code>Promise</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L229">View code</a></p>
<p>Associate several instances with this.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[newAssociations]</td>
<td>Array.&lt;Instance | String | Number&gt;</td>
<td>An array of instances or primary key of instances to associate with this.</td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>Options passed to <code>through.findAll</code>, <code>bulkCreate</code> and <code>update</code>. Can also hold additional attributes for the join table.</td>
</tr>
<tr>
<td>[options.validate]</td>
<td>Object</td>
<td>Run validation for the join model.</td>
</tr>
</tbody>
</table>
<hr>
<p><a name="addassociation"></a></p>
<h2 id="addassociationnewassociation-options-promise"><code>addAssociation([newAssociation], [options])</code> -&gt; <code>Promise</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L239">View code</a></p>
<p>Associate one instance with this.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[newAssociation]</td>
<td>Instance | String | Number</td>
<td>An instance or primary key of instance to associate with this.</td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>Options passed to <code>through.findAll</code>, <code>bulkCreate</code> and <code>update</code>. Can also hold additional attributes for the join table.</td>
</tr>
<tr>
<td>[options.validate]</td>
<td>Object</td>
<td>Run validation for the join model.</td>
</tr>
</tbody>
</table>
<hr>
<p><a name="createassociation"></a></p>
<h2 id="createassociationvalues-options-promise"><code>createAssociation([values], [options])</code> -&gt; <code>Promise</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L248">View code</a></p>
<p>Create a new instance of the associated model and associate it with this.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[values]</td>
<td>Object</td>
<td></td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>Options passed to create and add. Can also hold additional attributes for the join table</td>
</tr>
</tbody>
</table>
<hr>
<p><a name="removeassociation"></a></p>
<h2 id="removeassociationoldassociated-options-promise"><code>removeAssociation([oldAssociated], [options])</code> -&gt; <code>Promise</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L257">View code</a></p>
<p>Un-associate the instance.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[oldAssociated]</td>
<td>Instance | String | Number</td>
<td>Can be an Instance or its primary key</td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>Options passed to <code>through.destroy</code></td>
</tr>
</tbody>
</table>
<hr>
<p><a name="removeassociations"></a></p>
<h2 id="removeassociationsoldassociated-options-promise"><code>removeAssociations([oldAssociated], [options])</code> -&gt; <code>Promise</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L266">View code</a></p>
<p>Un-associate several instances.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[oldAssociated]</td>
<td>Array.&lt;Instance | String | Number&gt;</td>
<td>Can be an array of instances or their primary keys</td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>Options passed to <code>through.destroy</code></td>
</tr>
</tbody>
</table>
<hr>
<p><a name="hasassociation"></a></p>
<h2 id="hasassociationinstance-options-promise"><code>hasAssociation([instance], [options])</code> -&gt; <code>Promise</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L275">View code</a></p>
<p>Check if an instance is associated with this.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[instance]</td>
<td>Instance | String | Number</td>
<td>Can be an Instance or its primary key</td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>Options passed to getAssociations</td>
</tr>
</tbody>
</table>
<hr>
<p><a name="hasassociations"></a></p>
<h2 id="hasassociationsinstances-options-promise"><code>hasAssociations([instances], [options])</code> -&gt; <code>Promise</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L284">View code</a></p>
<p>Check if all instances are associated with this.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[instances]</td>
<td>Array.&lt;Instance | String | Number&gt;</td>
<td>Can be an array of instances or their primary keys</td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>Options passed to getAssociations</td>
</tr>
</tbody>
</table>
<hr>
<p><a name="countassociations"></a></p>
<h2 id="countassociationsoptions-promiseint"><code>countAssociations([options])</code> -&gt; <code>Promise.&lt;Int&gt;</code></h2>
<p><a href="https://github.com/sequelize/sequelize/blob/3e5b8772ef75169685fc96024366bca9958fee63/lib/associations/belongs-to-many.js#L294">View code</a></p>
<p>Count everything currently associated with this, using an optional where clause.</p>
<p><strong>Params:</strong></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[options]</td>
<td>Object</td>
<td></td>
</tr>
<tr>
<td>[options.where]</td>
<td>Object</td>
<td>An optional where clause to limit the associated models</td>
</tr>
<tr>
<td>[options.scope]</td>
<td>String | Boolean</td>
<td>Apply a scope on the related model, or remove its default scope by passing false</td>
</tr>
</tbody>
</table>
<hr>
<p><em>This document is automatically generated based on source code comments. Please do not edit it directly, as your changes will be ignored. Please write on <a href="irc://irc.freenode.net/#sequelizejs">IRC</a>, open an issue or a create a pull request if you feel something can be improved. For help on how to write source code documentation see <a href="http://usejsdoc.org">JSDoc</a> and <a href="https://github.com/tj/dox">dox</a></em></p>
              
            </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="/v3/hooks/" class="btn btn-neutral float-right" title="Hooks">Next <span class="icon icon-circle-arrow-right"></span></a>
      
      
        <a href="/v3/api/has-many/" class="btn btn-neutral" title="HasMany (1:m)"><span class="icon icon-circle-arrow-left"></span> Previous</a>
      
    </div>
  

  <hr>

  <div role="contentinfo">
    <!-- Copyright etc -->
    
  </div>

  Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
      
        </div>
      </div>

    </section>

  </div>

  <div class="rst-versions" role="note" aria-label="versions">
  <span class="rst-current-version" data-toggle="rst-current-version">
    
        <span>
          <a href="https://github.com/sequelize/sequelize/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
        </span>
    
    
      <span><a href="/v3/api/has-many/" style="color: #fcfcfc">« Previous</a></span>
    
    
      <span><a href="/v3/hooks/" style="color: #fcfcfc">Next »</a></span>
    
  </span>
</div>
    <script>var base_url = '../../..';</script>
    <script src="/v3/js/theme_extra.js" defer=""></script>
    <script src="/v3/js/theme.js" defer=""></script>
      <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/highlight.min.js" defer=""></script>
      <script src="/v3/search/main.js" defer=""></script>
    <script defer="">
        window.onload = function () {
            SphinxRtdTheme.Navigation.enable(true);
        };
    </script>



</body></html>